<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>OpenFlights: Widget</title>
    <link rel="stylesheet" href="/css/style_reset.css" type="text/css">
    <link rel="stylesheet" href="/openflights.css" type="text/css">
    <link rel="icon" type="image/png" href="/img/icon_favicon.png"/>
  </head>

  <body>
    <div id="mainContainer">
      <div id="sideBarContentWrapper">
	  
	<div id="contentContainer">
	  <div id="nonmap">
	    
	    <h1>OpenFlightsMap Widget</h1>
	    
	    <p>This is the documentation for the OpenFlightsMap widget, meant for programmers who want to reuse
	    the OpenFlights code in their own websites.  If this is not you, then you're probably in the wrong place.
	    How about taking a look at <a href="/data">our data</a> or <a href="/faq">the FAQ</a>?</p>

	      <p><i>The widget is a work in progress.  Suggestions about how to make the widget easier to setup, easier to use or more flexible are welcome!</i></p>

	    <h2>Demo</h2>

	    <p style="font-size: 1.5em; padding: 10px; background-color: #ccffcc;"><a target="_blank" href="/widget/demo">OpenFlightsMap Widget demo</a> (opens in new window)</p>
	    
	    <h2>Setting up</h2>

	    <p>OpenFlights is a client-server system, with a Javascript frontend (client) and a PHP/MySQL backend (server), and running the demo locally requires both.</p>

	      <p>To start, it's easiest just to grab the entire Git tree from GitHub:</p>

	      <p><tt>git clone https://github.com/jpatokal/openflights.git</tt></p>
	     
	      <p>Or <a href="https://github.com/jpatokal/openflights">browse online</a>.</p>

	      <h4>Server</h4>

	    <b>Requirements</b>
	      <ul>
		<li>Apache web server
		<li>MySQL 5.x database
		<li>PHP 5.x with <a href="http://www.gnu.org/software/gettext/">gettext</a>
	      </ul>

	    <p>Once you have these set up, the <tt>sql/create.sql</tt> script can be used to generate the OpenFlights
		database schema and the <tt>sql/load_data.sql</tt> script can be used to load in the standard
		airport, airline and route databases:</p>

	      <p><tt>mysql -u root &lt;sql/create.sql<br>
	      mysql -u openflights flightdb2 &lt;sql/load-data.sql</tt></p>

	    <p>OpenFlights differentiates between <b>flight</b> data (table <tt>flights</tt>), which is entered by
		users, and <b>route</b> data (table <tt>routes</tt>, which is data about what airlines fly where.
		While fundamentally the same -- every row has two airports and an optional airline -- the two differ
		in the additional details attached to the flights.  A clean install of OpenFlights has no flight data,
		but a full set of route data.</p>

	    <p>Flight map data sets are generated by <tt>php/map.php</tt>.
		Route map data is generated by <tt>php/routes.php</tt>.
		Both also require the <tt>locale.php, db.php, helper.php and filter.php</tt> files;
		you must modify <tt>db.php</tt> so that it can find your database.</p>

	      <p>To validate your server installation, try to open either of
	      the following URLs in a browser:</p>
	      <p>
	      <table>
		<tr>
		  <td><tt>http://localhost/php/map.php</tt></td>
		  <td>0;0 miles;;O;;demo;;[sessionkey]</td>
		</tr>
		<tr>
		  <td><tt>http://localhost/php/routes.php?apid=32</tt></td>
		  <td>32;6;Cambridge Bay (YCB) ...</td>
		</tr>
	      </table>
	      <p>If you get any errors, check the Apache log
	      (<tt>/var/log/apache2/error.log</tt>).</p>
	      
	      <p>Note: The above is just a sanity check, <i>do not attempt to parse responses from map.php or routes.php manually</i>.  The format is undocumented and unstable.</i></p>

	      <h4>Client</h4>

	      <p>A web page using the OpenFlightsMap widget, such as <tt>widget/demo.html</tt> (<a target="_blank" href="/widget/demo">launch</a>), must include the following:</p>

<pre>
&lt;link rel="stylesheet" href="demo.css" type="text/css"&gt;
&lt;script type="text/javascript" src="/js/OpenLayers.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="/js/map.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="/js/Gettext.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="/js/prototype.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="demo.js"&gt;&lt;/script&gt;
</pre>
	      
	      <p>One by one:</p>
	      <ul>
		<li>Your CSS file (<tt>demo.css</tt>) must define your map element (<tt>#map</tt>, although this can be renamed),
		  the map title (#maptitle), a "Loading" icon (#ajaxloader) and, optionally, a #debug element.  The CSS required by the underlying <a href="http://openlayers.org">OpenLayers</a> library is also included here.</li>

		<li>The OpenLayers library (<tt>OpenLayers.js</tt>), version 1.7 or higher.
		<li>The OpenFlightsMap class itself (<tt><a href="/widget/jsdoc/OpenFlightsMap.html">map.js</a></tt>).
		<li>The JSGetText library (<tt>Gettext.js</tt>), for localization.  Locale files are accessed from <tt>locale</tt>; however, if they're missing, OpenFlights defaults to English.  On Linux systems, you may also need to set up your operating system locale, see <a href="http://openflights.org/blog/2009/05/29/dynamic-javascript-localization-with-gettext-and-php/">Dynamic Javascript localization with Gettext and PHP</a> for details.
		<li>The <a href="http://www.prototypejs.org">Prototype</a> library, for AJAX and other Javascript magic.
		<li>The code that initializes and run the widget (<tt><a href="/widget/jsdoc/overview-summary-demo.js.html">demo.js</a></tt>).
	      </ul>

	      <p>Once you've got all that set up, to actually initialize your widget, you need to:</p>
	      <ol>
		<li>Set up an OpenLayers map layer
		<li>Pass a suitable DOM element (by default "map") and the layer to the OpenFlightsMap constructor
		<li>Load the map data from the server
	      </ol>

	      <p>To catch the user's clicks on airports, you'll also want to set up the <tt>onAirportSelect()</tt>
		and <tt>onAirportUnselect()</tt> callbacks.  All this and more is demonstrated in <tt><a href="https://github.com/jpatokal/openflights/blob/master/widget/demo.html">widget/demo.html</a></tt>.</p>

	      <p>If you encounter any problems getting demo.html to
	    run (blank map, error messages etc), check the error
	    console of your browser (Tools &gt; Error Console on
	    Firefox) for clues.</p>
	      
	    <h2>Documentation</h2>

	    <p>The autogenerated JSDocs for OpenFlightsMap class and <tt>widget/demo.html</tt> are available under <a href="/widget/jsdoc/">widget/jsdoc</a>.</p>

	      <br/>
	      <br/>
	  </div>
	</div> 
	
	<div id="sideBar">
        <!--#include virtual="/sidebar.html" -->
        <!--#include virtual="/html/ad-sidebar.html" -->
	</div>

      </div> <!-- end sidebarwrapper -->
    </div> <!-- end mainContainer -->

  </body>
</html>
